ATOM Documentation

ATOM SaaS - Quick Start Guide

🚀 Quick Start

This guide will get your ATOM SaaS platform running in minutes.

1. Environment Setup

# Copy environment template
cp .env.example .env.local

# Edit .env.local with your configuration
# Required variables:
# - DATABASE_URL (Neon PostgreSQL)
# - JWT_SECRET (generate a random string)
# - AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_S3_BUCKET
# - STRIPE_SECRET_KEY, STRIPE_PUBLISHABLE_KEY
# - SMTP_HOST, SMTP_USER, SMTP_PASS (for emails)

2. Install Dependencies

npm install

3. Database Setup

# Run database migrations and seed data
npm run setup:dev

4. Start Development Server

npm run dev

Your platform will be available at:

• **Marketing Site**: http://localhost:3000
• **Admin Dashboard**: http://localhost:3000/admin
• **Demo Tenant**: http://localhost:3000 (automatic redirect)

5. Default Login Credentials

**Admin Account:**

• Email: admin@atom-saas.com
• Password: admin123 (change this in production!)

**Demo Tenant:**

• Subdomain: demo
• Email: admin@demo.com
• Password: demo123

🔧 Configuration

Database

• **Recommended**: Neon Serverless PostgreSQL
• **Local**: PostgreSQL 14+
• **Connection**: Use connection string in DATABASE_URL

Storage

• **Required**: AWS S3 bucket
• **Settings**: Configure in .env.local
• **Structure**: Automatic per-tenant prefix organization

Email

• **Recommended**: Resend, SendGrid, or Postmark
• **SMTP**: Configure with your provider
• **Templates**: Automatic email workflows included

Payment

• **Required**: Stripe account
• **Test**: Use test keys during development
• **Webhooks**: Configure webhook endpoint

📁 Project Structure

atom-saas/
├── src/
│   ├── app/                 # Next.js App Router
│   │   ├── admin/         # Admin dashboard routes
│   │   ├── api/           # API routes
│   │   └── auth/          # Authentication pages
│   ├── components/         # React components
│   │   ├── admin/         # Admin UI components
│   │   ├── ui/           # Reusable UI components
│   │   └── layout/       # Layout components
│   ├── lib/               # Core libraries
│   │   ├── auth.ts        # NextAuth configuration
│   │   ├── database.ts    # Database service
│   │   ├── email.ts       # Email service
│   │   ├── storage.ts     # S3 storage service
│   │   └── admin-auth.ts # Admin authentication
│   └── middleware.ts       # Request middleware
├── database/               # SQL schemas
├── scripts/               # Utility scripts
└── docs/                  # Documentation

🎯 Next Steps

1. **Configure External Services**: Set up your Neon, AWS, Stripe, and email accounts
2. **Customize Branding**: Update colors, logos, and content
3. **Test Flows**: Verify tenant creation, user management, and billing
4. **Deploy**: Use ATOM Cloud or your preferred hosting platform
5. **Monitor**: Set up analytics and alerting

🛠️ Development Commands

# Development
npm run dev              # Start dev server
npm run build            # Build for production
npm run start            # Start production server

# Database
npm run db:migrate       # Run migrations
npm run db:seed          # Seed initial data
npm run db:reset         # Reset database (destructive!)

# Quality
npm run lint             # Run ESLint
npm run type-check       # TypeScript type checking
npm run test             # Run tests
npm run test:coverage    # Test coverage report

🔐 Security Notes

• **Change Default Passwords**: Update admin credentials in production
• **Environment Variables**: Never commit .env.local files
• **HTTPS Required**: Use HTTPS in production (especially for OAuth)
• **Database Security**: Enable connection encryption
• **API Keys**: Rotate API keys regularly

📊 Monitoring

The platform includes comprehensive monitoring:

• **Health Checks**: /api/health
• **Admin Analytics**: Full dashboard with metrics
• **Error Tracking**: Detailed error logging and reporting
• **Usage Analytics**: Tenant and system-wide usage tracking

ATOM Cloud (Recommended)

# Install ATOM CLI
curl -fsSL https://get.atomagentos.com/install.sh | bash

# Deploy
atom-cli deploy

Other Platforms

The platform is container-ready and can be deployed on:

• AWS (ECS, Lambda)
• Google Cloud (Run, Cloud Run)
• Azure (Container Instances)
• DigitalOcean (App Platform)
• Heroku (Container Registry)

🆘 Getting Help

1. **Documentation**: Check /docs folder for detailed guides
2. **Health Check**: Run npm run health to verify services
3. **Logs**: Check browser console and server logs
4. **Issues**: Review database migrations and environment setup

✅ Verification Checklist

After setup, verify:

• [ ] Marketing site loads at localhost:3000
• [ ] Admin dashboard accessible at localhost:3000/admin
• [ ] Demo tenant routing works
• [ ] Database migrations completed successfully
• [ ] Email service configured
• [ ] Storage service accessible
• [ ] All environment variables set

---

🎉 **Congratulations!** Your ATOM SaaS platform is ready for development and testing.

Need help? Check the detailed documentation in the /docs folder or run npm run health to verify your setup.